{/* Copyright 2020 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:@react-spectrum/switch';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/switch/package.json';

```jsx import
import {Switch} from '@react-spectrum/switch';
```

---
category: Forms
keywords: [switch, toggle, input]
---

# Switch

<PageDescription>{docs.exports.Switch.description}</PageDescription>

<HeaderInfo
  packageData={packageData}
  componentNames={['Switch']}
  sourceData={[
    {type: 'Spectrum', url: 'https://spectrum.adobe.com/page/switch/'}
  ]}
  since="3.0.0" />

## Example

```tsx example
<Switch>Low power mode</Switch>

```

## Content

Switches accept children, which are rendered as the label.

Switches are best used for communicating activation (e.g. on/off states), while [checkboxes](./Checkbox.html) are best used for communicating selection (e.g. multiple table rows).
Switches, unlike checkboxes, can't have an error state.

### Accessibility

In certain cases a visible label isn't needed. For example, a Switch located at the top of a panel which toggles the panels options on or off.
If a visible label isn't specified, an `aria-label` must be provided to the Switch for accessibility.
If the field is labeled by a separate element, an `aria-labelledby` prop must be provided using the id of the labeling element instead.

```tsx example
<Switch aria-label="Low power mode" />
```

### Internationalization

To internationalize a Switch, a localized label should be passed to the `children` or `aria-label` prop.
For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the switch is automatically flipped.

## Value

Switches are not selected by default. The `defaultSelected` prop can be used to set the default state (uncontrolled).
Alternatively, the `isSelected` prop can be used to make the selected state controlled.

```tsx example
function Example() {
  let [selected, setSelection] = React.useState(false);

  return (
    <>
      <Switch
        defaultSelected>
        Low power mode (uncontrolled)
      </Switch>

      <Switch
        isSelected={selected}
        onChange={setSelection}>
        Low power mode (controlled)
      </Switch>
    </>
  )
}
```

### HTML forms

Switch supports the `name` and `value` props for integration with HTML forms.

```tsx example
<Switch name="power" value="low">Low power mode</Switch>
```

## Events

Switches accept a user defined `onChange` prop, triggered whenever the Switch is pressed.
The example below uses `onChange` to alert the user to changes in state.

```tsx example
function Example() {
  let [selected, setSelection] = React.useState(false);

  return (
    <>
      <Switch onChange={setSelection}>
        Switch Label
      </Switch>
      <div>The Switch is on: {selected.toString()}</div>
    </>
  );
}
```

## Props

<PropTable component={docs.exports.Switch} links={docs.links} />

## Visual options

### Disabled
[View guidelines](https://spectrum.adobe.com/page/switch/#Disabled)

```tsx example
<Switch isDisabled>Switch Label</Switch>
```

### Emphasized
[View guidelines](https://spectrum.adobe.com/page/switch/#Emphasized-or-not?)

```tsx example
<Switch isEmphasized defaultSelected>Switch Label</Switch>
```

### Read only

```tsx example
<Switch isReadOnly isSelected>Switch Label</Switch>
```
